4.1 本章介绍

🎯 一句话理解 Spec-kit

Spec-kit 是规格说明书驱动开发（Specification-Driven Development）的工具包，让"需求文档"成为可执行的蓝图，而不仅仅是计划阶段的脚手架。

想象一下：

你的产品需求文档不再是写完就被遗忘的文件
当需求变更时，代码可以从更新的规格说明书重新生成
团队的前端、后端、设计师都基于同一份规格文档协作
AI 助手能够理解你的意图，并严格按照规范实现功能

这就是 Spec-kit 要解决的问题。

💡 为什么需要 Spec-kit？

传统开发的痛点

痛点 1：规格与实现脱节

产品经理写需求文档
    ↓
开发理解需求（可能有偏差）
    ↓
开发写代码
    ↓
需求变更...
    ↓
文档过时了！（没人更新文档）
    ↓
代码变成唯一的"真相来源"

痛点 2：手工翻译的开销

需求："用户可以创建相册"
   ↓ （开发人员手工翻译）
数据模型：Album { id, user_id, title, photos[], created_at }
API 接口：POST /api/albums
前端组件：AlbumCreator.tsx
测试用例：test_album_creation.py

💥 问题：每次需求变更，所有这些都要手工同步！

痛点 3：团队沟通成本

前端开发："后端的 API 什么时候好？"
后端开发："你们前端的 UI 长什么样？"
产品经理："这个功能到底做成什么样了？"
设计师："这个按钮应该放哪里？"

💥 每个人对需求的理解都不同！

Spec-kit 如何解决

解决方案 1：规格成为源头

spec.md（规格说明书，技术无关）
   ├─→ plan.md（技术方案：Python? React? Go?）
   ├─→ tasks.md（任务分解：先做什么后做什么）
   └─→ code（代码是规格的表达，不是源头）

✅ 需求变更？更新 spec.md → 重新生成代码
✅ 文档永远是最新的（因为代码是从文档生成的）

解决方案 2：AI 自动翻译

你的输入（自然语言）：
"用户可以创建相册"

Spec-kit + AI 自动生成：
✓ 数据模型
✓ API 接口
✓ 测试用例
✓ 前端组件

✅ 节省 ~12 小时手工文档时间 → ~15 分钟

解决方案 3：团队对齐

同一份 spec.md
   ├─→ 后端开发基于这个规格实现 API
   ├─→ 前端开发基于这个规格实现 UI
   ├─→ 测试基于这个规格编写测试
   └─→ 产品经理基于这个规格验收

✅ 所有人看同一份文档，零理解偏差

🚀 Spec-kit 的核心理念

核心理念 1：Intent-Driven Development（意图驱动开发）

传统方式：

开发者思考：用 React 还是 Vue？用 MySQL 还是 Postgres？
           怎么实现这个功能？用什么设计模式？

💥 问题：过早关注"How"（怎么做），忽略"What"（做什么）和"Why"（为什么）

Spec-kit 方式：

第 1 步：spec.md（只写 What 和 Why）
   "用户可以创建相册来组织照片"
   （不提任何技术：React、Vue、数据库...）

第 2 步：plan.md（确定 How）
   "用 React + Supabase 实现"
   （技术选型推迟到这一步）

第 3 步：tasks.md + code
   AI 按照 plan 生成代码

✅ 先明确意图，再选技术
✅ 同一个 spec 可以生成 Python 版、Go 版、JavaScript 版

核心理念 2：Specifications as Executable Blueprints（规格即可执行蓝图）

传统文档：

需求文档.docx（写完就不管了）
    ↓
代码（手工实现）
    ↓
测试（手工编写）
    ↓
需求变更...
    ↓
文档没人更新 ❌

Spec-kit 文档：

spec.md（活的文档）
    ↓
AI 自动生成 plan.md, tasks.md, code, tests
    ↓
需求变更...
    ↓
更新 spec.md → 重新生成代码 ✅

关键区别：

传统文档	Spec-kit 文档
静态的、一次性的	活的、可迭代的
代码是源头	规格是源头
文档会过时	文档永远最新
手工同步	自动同步

核心理念 3：Constitutional Framework（宪法框架）

问题：

团队 A 的开发者：喜欢用 10 个库
团队 B 的开发者：喜欢用 3 个库
团队 C 的开发者：不写测试
团队 D 的开发者：测试先行

💥 每个团队风格不同，代码质量参差不齐

Spec-kit 的 Constitution（宪法）：

markdown

# 项目宪法

## 第 1 条：简洁优先
项目必须使用 ≤3 个外部依赖

## 第 2 条：CLI 优先
所有功能必须提供命令行接口

## 第 3 条：测试驱动开发（TDD）
所有代码必须先写测试再写实现

✅ 这些是"不可协商"的原则
✅ 所有 plan 必须通过宪法检查
✅ AI 会自动验证是否违反宪法

效果：

开发者 A 想用 10 个库
   ↓
AI 检查宪法："违反第 1 条（≤3 个依赖）"
   ↓
❌ 阻止实现，要求重新设计

开发者 B 忘记写测试
   ↓
AI 检查宪法："违反第 3 条（TDD）"
   ↓
❌ 提醒：请先写测试

📚 快速案例说明

案例 1：个人项目 - 相册管理器（5 分钟体验）

你的需求：

我想做一个相册管理器，用户可以：
- 创建相册
- 上传照片到相册
- 查看相册里的照片

使用 Spec-kit 的流程：

Step 1: 初始化项目

bash

specify init photo-album --ai claude
cd photo-album

Step 2: 创建宪法（可选，但推荐）

bash

/speckit.constitution

AI 会问你一些问题：

Q: 这个项目有什么不可协商的原则吗？
A: 静态网站，不用服务器，只用 HTML/CSS/JavaScript

宪法生成：
✓ 第 1 条：静态网站，无服务端
✓ 第 2 条：不用前端框架（React、Vue 等）
✓ 第 3 条：最小依赖

Step 3: 写规格

bash

/speckit.specify 用户可以创建相册，上传照片，并查看相册

AI 自动生成 specs/001-photo-album/spec.md：

markdown

## 用户故事

### P1: 创建相册
**作为** 摄影爱好者
**我想要** 创建相册
**以便** 组织我的照片

#### 验收标准
- 给定用户在主页
- 当用户点击"创建相册"
- 那么显示相册创建表单
- 并且用户可以输入相册名称
- 并且保存后相册出现在列表中

### P2: 上传照片
...

## 功能需求
- 必须支持创建相册
- 必须支持上传照片（JPG, PNG）
- 应该显示照片缩略图

## 成功标准
- 相册创建在 2 秒内完成
- 支持至少 10,000 张照片

Step 4: 技术方案

bash

/speckit.plan 用 Vite + 原生 JavaScript，照片存储在浏览器 IndexedDB

AI 生成 specs/001-photo-album/plan.md：

markdown

## 技术栈
- 构建工具：Vite
- 前端：原生 JavaScript
- 存储：IndexedDB

## 数据模型
```javascript
// Album
{
  id: string,
  title: string,
  photos: Photo[],
  created_at: timestamp
}

// Photo
{
  id: string,
  album_id: string,
  data: blob,
  uploaded_at: timestamp
}

宪法检查

✅ 无服务端（符合第 1 条） ✅ 无框架（符合第 2 条） ✅ 最小依赖：仅 Vite（符合第 3 条）


**Step 5: 任务分解**
```bash
/speckit.tasks

生成任务列表：

markdown

## 阶段 1：初始化
- [ ] T001 用 Vite 初始化项目
- [ ] T002 配置 IndexedDB

## 阶段 2：用户故事 1 - 创建相册
- [ ] T003 [US1] 创建相册表单 UI
- [ ] T004 [US1] 实现相册保存到 IndexedDB
- [ ] T005 [US1] 显示相册列表

## 阶段 3：用户故事 2 - 上传照片
- [ ] T006 [US2] 创建照片上传组件
- [ ] T007 [US2] 保存照片到 IndexedDB
- [ ] T008 [US2] 显示照片缩略图

Step 6: 实现

bash

/speckit.implement

AI 按照任务列表一步步实现代码，你只需要验收！

结果：

耗时：~15 分钟（如果手工写需要 2-4 小时）
质量：符合你的宪法要求
文档：自动生成，永远最新

案例 2：团队项目 - API 开发（企业级）

场景：

后端团队（3 人）+ 前端团队（3 人）
需求：开发用户认证系统

传统方式的问题：

产品经理写需求 PRD（10 页 Word 文档）
   ↓
后端理解需求 → 设计 API
   ↓
前端等后端 API 完成
   ↓
后端 API 完成，前端开始对接
   ↓
发现理解不一致 → 返工 💥

Spec-kit 方式：

Step 1: 产品经理写规格（1 小时）

bash

/speckit.specify 用户注册系统，支持邮箱注册、密码重置、邮箱验证

生成 specs/001-user-auth/spec.md：

markdown

## 用户故事

### P1: 邮箱注册
- 用户输入邮箱和密码
- 系统发送验证邮件
- 用户点击验证链接激活账号

## 功能需求
- 必须验证邮箱格式
- 密码必须 ≥8 位，包含大小写字母和数字
- 验证邮件必须在 30 秒内发送

## 成功标准
- 注册流程 < 3 分钟完成
- 90% 的验证邮件在 30 秒内送达

Step 2: 后端团队生成技术方案（30 分钟）

bash

/speckit.plan FastAPI + PostgreSQL + Redis + JWT

生成 API 契约（OpenAPI 规范）：

yaml

# specs/001-user-auth/contracts/api.yaml
POST /api/users/register
  Request:
    email: string
    password: string
  Response 201:
    user_id: integer
    message: "Verification email sent"
  Response 409:
    error: "Email already registered"

Step 3: 前端团队并行开发（基于同一个 spec）

bash

/speckit.plan React TypeScript，使用后端的 API 契约

关键点：

前后端基于同一份 spec.md 和 API 契约
前端可以用 Mock 服务器模拟后端 API（基于契约）
后端和前端并行开发，不用等待
集成时零惊喜（因为都遵循同一个契约）

效果：

耗时：节省 ~40% 沟通时间
质量：API 契约保证前后端一致
文档：OpenAPI 自动生成 API 文档

案例 3：多方案探索（创业团队）

场景：

创业团队不确定用 React 还是 Vue
也不确定后端用 Python 还是 Node.js

传统方式：

猜一个技术栈 → 全部实现 → 发现不合适 → 返工 💥

Spec-kit 方式：

Step 1: 写一份规格（技术无关）

bash

/speckit.specify 用户仪表盘，显示任务统计、最近活动、快速操作

Step 2: 生成 3 个并行的技术方案

bash

# 方案 A：React + Node.js
/speckit.plan React + Node.js + MongoDB
mv specs/001-dashboard/plan.md specs/001-dashboard/plan-react-node.md

# 方案 B：Vue + Python
/speckit.plan Vue + Python FastAPI + PostgreSQL
mv specs/001-dashboard/plan.md specs/001-dashboard/plan-vue-python.md

# 方案 C：Svelte + Go
/speckit.plan Svelte + Go + SQLite
mv specs/001-dashboard/plan.md specs/001-dashboard/plan-svelte-go.md

Step 3: 分别实现（3 个开发者并行）

bash

# 开发者 A
/speckit.implement --plan=plan-react-node.md

# 开发者 B
/speckit.implement --plan=plan-vue-python.md

# 开发者 C
/speckit.implement --plan=plan-svelte-go.md

Step 4: 对比测试

测试性能、开发体验、部署难度
选择最优方案
丢弃其他方案（不浪费规格编写时间，因为只写了一次）

效果：

零浪费：规格只写一次
快速验证：3 个方案并行实现
数据驱动：基于实际数据选择技术栈

🔍 Spec-kit vs 其他工具

Spec-kit vs Claude Code Skills

维度	Spec-kit	Skills
定位	开发方法论 + 工作流	专业知识库 + 工作流程
用途	结构化功能开发	重复性任务的专业指导
触发	手动命令（/speckit.specify）	自动匹配 description
输出	规格文档 + 代码	增强 Claude 的领域能力
适用场景	新功能、架构规范	品牌指南、Excel 报表
互补性	✅ 高度互补	✅ 高度互补

组合使用示例：

bash

# 用 Spec-kit 构建功能
/speckit.specify 构建财务报表仪表盘

# 用 Skills 提供 Excel 导出的专业知识
/speckit.plan 用 Excel 导出，遵循公司格式标准
            ↑（Skills 提供 Excel 格式的专业知识）

# Spec-kit: 结构化开发流程
# Skills: 提供 Excel 格式的最佳实践

Spec-kit vs MCP（Model Context Protocol）

维度	Spec-kit	MCP
定位	开发工作流结构	外部系统连接
功能	指导开发过程	访问数据库、API、SaaS
复杂度	简单（Markdown 文件）	复杂（协议实现）
适用场景	组织开发流程	连接外部数据源
互补性	✅ 高度互补	✅ 高度互补

关键区别：

MCP: "连接 Claude 到数据"（数据库、API）
Spec-kit: "教 Claude 如何处理这些数据"（开发流程）
Skills: "教 Claude 领域知识"（Excel、品牌规范）

完整堆栈示例：

bash

# MCP：连接到 PostgreSQL 数据库
# Skills：提供数据分析的最佳实践
# Spec-kit：结构化开发流程

/speckit.specify 构建用户分析仪表盘
/speckit.plan 用 PostgreSQL（通过 MCP）+ 遵循公司仪表盘标准（通过 Skills）
/speckit.implement
   ↓
   使用 MCP 查询数据库
   应用 Skills 的分析方法
   遵循 Spec-kit 的开发流程

什么时候用 Spec-kit？

场景	推荐工具	原因
新功能开发（2+ 天）	Spec-kit	强制前期明确需求
快速原型（< 4 小时）	直接提示词	结构化开销不值得
访问外部数据库	MCP	直接数据连接
重复性格式化任务	Skills	领域专业知识
团队协作	Spec-kit	共享规格对齐团队
一次性脚本	直接提示词	无需结构化
遵循品牌规范	Skills	程序性知识
遗留系统现代化	Spec-kit	捕获原始业务逻辑

🎓 本章学习路线

初学者路径（第 1 周）

目标： 理解 Spec-kit 核心概念，完成第一个项目

第 1-2 天：理解核心理念
├─ 阅读本章（4.1）
├─ 理解 Spec-kit vs Skills vs MCP 区别
└─ 安装 Spec-kit 工具

第 3-4 天：第一个项目
├─ 创建简单静态网站（个人作品集）
├─ 体验完整流程：specify → plan → tasks → implement
└─ 理解 spec.md（What）vs plan.md（How）分离

第 5 天：练习与总结
├─ 创建第二个项目（相册管理器）
├─ 体验宪法（Constitution）机制
└─ 总结学习心得

学习重点：

✅ 理解"规格即源头"的理念
✅ 掌握基本工作流（6 个步骤）
✅ 区分 spec（What）和 plan（How）
✅ 体验 AI 自动生成代码

进阶路径（第 2 周）

目标： 掌握高级技巧，团队协作

第 1-2 天：API 开发
├─ 创建 REST API 项目
├─ 学习 OpenAPI 契约优先开发
├─ 理解前后端并行开发

第 3-4 天：多方案探索
├─ 同一个 spec，生成 3 个技术方案
├─ 对比不同技术栈
└─ 理解技术无关规格的价值

第 5 天：团队协作
├─ 创建团队宪法
├─ 模拟团队协作场景
└─ 学习 CI/CD 集成

学习重点：

✅ 契约优先开发（Contract-First）
✅ 宪法框架（Constitutional Framework）
✅ 多方案并行探索
✅ 团队协作模式

专家路径（第 3+ 周）

目标： 定制化 Spec-kit，企业级应用

第 1-2 天：定制化
├─ 创建自定义命令
├─ 修改模板
├─ 编写自定义验证脚本

第 3-4 天：企业集成
├─ CI/CD 流水线集成
├─ 多工具协同（Spec-kit + MCP + Skills）
└─ 安全合规验证

第 5+ 天：实战项目
├─ 遗留系统现代化
├─ 大型团队协作
└─ 分享最佳实践

学习重点：

✅ 自定义扩展
✅ 企业级工作流
✅ 复杂场景应对
✅ 最佳实践总结

📖 本章内容概览

4.2 - Spec-kit 基础概念和结构

Spec-kit 的核心组件（spec.md, plan.md, tasks.md）
6 阶段工作流详解
文件结构和命名规范
与 Claude Code 的集成机制

4.3 - 创建你的第一个 Spec

示例 1（5 分钟）： 个人作品集网站
示例 2（30 分钟）： 相册管理器
示例 3（60 分钟）： 待办事项 API
完整工作流实战演练

4.4 - 进阶技巧和最佳实践

宪法框架（Constitution）深度应用
契约优先开发（Contract-First Development）
多技术栈并行探索
团队协作模式
CI/CD 集成
调试与故障排查

4.5 - 本章小结

核心知识点回顾
常见问题 FAQ
快速参考指南
学习资源推荐

💬 开始之前的建议

✅ 推荐做法

先理解理念，再学工具
- 理解"为什么"比"怎么用"更重要
- Spec-kit 是方法论，不仅仅是工具
从小项目开始
- 第一个项目用 1-2 小时完成
- 不要一开始就做复杂系统
亲自动手
- 光看不练假把式
- 每个示例都要跟着做一遍
理解分离关注点
- spec.md = What & Why（做什么，为什么）
- plan.md = How（怎么做）
- 不要在 spec 里写技术细节
善用宪法
- 为你的项目定义不可协商的原则
- 让 AI 自动验证合规性

❌ 常见误区

误区 1：Spec-kit 是代码生成器

❌ 错误理解：输入需求 → 自动生成完美代码
✅ 正确理解：输入意图 → 结构化开发流程 → AI 辅助实现

误区 2：所有项目都要用 Spec-kit

❌ 不适合：一次性脚本、快速原型
✅ 适合：2+ 天功能、团队协作、需要文档

误区 3：spec.md 要写技术细节

❌ 错误："用 React + PostgreSQL 实现用户注册"
✅ 正确："用户可以通过邮箱注册账号"

误区 4：plan 阶段可以跳过

❌ 错误：specify → 直接 implement
✅ 正确：specify → plan → tasks → implement

🚀 准备好了吗？

恭喜你完成了 Spec-kit 的入门介绍！现在你应该理解了：

✅ Spec-kit 是什么（规格驱动开发工具包） ✅ 为什么需要它（解决规格与实现脱节） ✅ 核心理念（意图驱动、规格可执行、宪法框架） ✅ 与 Skills、MCP 的区别和互补性 ✅ 何时使用 Spec-kit

下一步： 4.2 Spec-kit 基础概念和结构 - 深入理解 Spec-kit 的工作原理！

Spec-kit 核心概念教程 v1.0 | 2025 Edition | 基于 GitHub Spec-kit 官方仓库

4.1 本章介绍 ​

🎯 一句话理解 Spec-kit ​

💡 为什么需要 Spec-kit？ ​

传统开发的痛点 ​

Spec-kit 如何解决 ​

🚀 Spec-kit 的核心理念 ​

核心理念 1：Intent-Driven Development（意图驱动开发） ​

核心理念 2：Specifications as Executable Blueprints（规格即可执行蓝图） ​

核心理念 3：Constitutional Framework（宪法框架） ​

📚 快速案例说明 ​

案例 1：个人项目 - 相册管理器（5 分钟体验） ​

宪法检查 ​

案例 2：团队项目 - API 开发（企业级） ​

案例 3：多方案探索（创业团队） ​

🔍 Spec-kit vs 其他工具 ​

Spec-kit vs Claude Code Skills ​

Spec-kit vs MCP（Model Context Protocol） ​

什么时候用 Spec-kit？ ​

🎓 本章学习路线 ​

初学者路径（第 1 周） ​

进阶路径（第 2 周） ​

专家路径（第 3+ 周） ​

📖 本章内容概览 ​

4.2 - Spec-kit 基础概念和结构 ​

4.3 - 创建你的第一个 Spec ​

4.4 - 进阶技巧和最佳实践 ​

4.5 - 本章小结 ​

💬 开始之前的建议 ​

✅ 推荐做法 ​

❌ 常见误区 ​

🚀 准备好了吗？ ​

4.1 本章介绍

🎯 一句话理解 Spec-kit

💡 为什么需要 Spec-kit？

传统开发的痛点

Spec-kit 如何解决

🚀 Spec-kit 的核心理念

核心理念 1：Intent-Driven Development（意图驱动开发）

核心理念 2：Specifications as Executable Blueprints（规格即可执行蓝图）

核心理念 3：Constitutional Framework（宪法框架）

📚 快速案例说明

案例 1：个人项目 - 相册管理器（5 分钟体验）

宪法检查

案例 2：团队项目 - API 开发（企业级）

案例 3：多方案探索（创业团队）

🔍 Spec-kit vs 其他工具

Spec-kit vs Claude Code Skills

Spec-kit vs MCP（Model Context Protocol）

什么时候用 Spec-kit？

🎓 本章学习路线

初学者路径（第 1 周）

进阶路径（第 2 周）

专家路径（第 3+ 周）

📖 本章内容概览

4.2 - Spec-kit 基础概念和结构

4.3 - 创建你的第一个 Spec

4.4 - 进阶技巧和最佳实践

4.5 - 本章小结

💬 开始之前的建议

✅ 推荐做法

❌ 常见误区

🚀 准备好了吗？